home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Cream of the Crop 26
/
Cream of the Crop 26.iso
/
program
/
wsc4d21.zip
/
WSC4D_U.TXT
< prev
next >
Wrap
Text File
|
1997-06-09
|
45KB
|
1,202 lines
Windows Standard Communications
Library for Delphi
(WSC4D)
USERS MANUAL
Version 2.1
June 9, 1997
This software is provided as-is.
There are no warranties, expressed or implied.
Copyright (C) 1996-1997
All rights reserved
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815
Voice : 205-881-4630
FAX : 205|880|0925
BBS : 205-880-9748
email : info@marshallsoft.com
web : www.marshallsoft.com
_______
____|__ | (R)
--+ | +-------------------
| ____|__ | Association of
| | |_| Shareware
|__| o | Professionals
--+--+ | +---------------------
|___|___| MEMBER
MARSHALLSOFT is a trademark of MarshallSoft Computing, Inc.
WSC4D Users Manual Page 1
C O N T E N T S
Chapter Page
1.0 Introduction................................................3
1.1 User Support............................................4
1.2 ASP Ombudsman...........................................4
1.3 Determining UART Address & IRQ Settings.................5
1.4 Installation............................................6
2.0 Library Overview............................................7
2.1 Dynamic Link Libraries..................................7
2.2 Using the Library.......................................7
2.3 Compiling Programs......................................7
2.4 Source Code.............................................7
3.0 Talking to Your Modem.......................................8
3.1 Modem Standards.........................................8
3.2 Flow Control...........................................10
3.3 Modem Initialization...................................10
4.0 Modem I/O..................................................11
4.1 MIO Introduction.......................................11
4.2 MIO Function Summary...................................11
5.0 XMODEM & YMODEM ...........................................12
5.1 XYDRIVER Introduction..................................12
5.2 XYDRIVER Function Summary..............................12
6.0 Problems...................................................13
7.0 Serial Communications......................................14
7.1 Communications Basics..................................14
7.2 RS232 Signals..........................................15
8.0 Example Programs...........................................16
8.1 SIMPLE.................................................16
8.2 SELFTEST...............................................16
8.3 MODEM..................................................16
8.4 TERM...................................................16
8.5 FIND...................................................16
9.0 Legal Issues................................................19
9.1 Registration............................................18
9.2 License.................................................18
9.3 Warranty................................................18
10.0 Summary....................................................19
10.1 Revision History.......................................19
10.2 WSC Function Summary...................................19
10.3 Further Reading........................................20
11.0 Other MarshallSoft Computing Products......................20
11.1 Personal Communications Library for Windows............20
11.2 Personal Communications Library for C/C++..............20
11.3 Libraries for Other Languages..........................20
WSC4D Users Manual Page 2
1.0 Introduction
The Windows Standard Communications Library for Delphi (WSC4D) is an
asynchronous communications dynamic link library (DLL) which uses the
standard Windows serial communications API. Since it uses the Windows
API, programs using the WSC library are fully compatible with other
Window applications which also use the Windows serial communications
API. Both Win16 and Win32 versions are included.
Using WSC is very straight-forward. For example, to write 'HELLO' to
the serial port COM1:
Code := SioReset(COM1,512,512); (* open COM1 *)
Code := SioPuts(COM1,'HELLO',5); (* write 'HELLO' to COM1 *)
Code := SioDone(COM1); (* close COM1 *)
Five Delphi example programs with full source code are included.
Refer to chapter 8 for more details on each of the example programs.
SIMPLE : A simple terminal emulator.
SELFTEST : Performs COM port functionality testing.
MODEM : Same as SIMPLE but controls flow control, modem
lines, etc.
TERM : Terminal emulator with XMODEM & YMODEM.
FIND : Finds connected modem.
WSC4D contains over 30 functions. All functions return a negative
number if an error condition is detected. For more details, consult
the WSC4D Reference Manual
WSC4D uses the same function names and arguments as PCL4W (our
Windows Communications Library that does NOT use the Windows API)
except for a few functions.
Our goal is to provide a robust serial communications library that
that you and your customers can depend upon. Contact us if you have
any questions.
The shareware and registered versions are identical except for two
differences: (1) the shareware version displays the 'shareware'
screen, and (2) the shareware version will 'time out' after 20
minutes, limiting execution to a maximum of twenty minutes each time
a program is run. Of course, the registered version does not display
the shareware screen nor time out after twenty minutes.
We apologize for the inconvenience of the shareware screen and
time-outs, but it is necessary to encourage registration by some who
would use the library (sometimes for years) without registering.
WSC4D Users Manual Page 3
1.1 User Support
We want you to be successful in developing your applications using
WSC4D! We depend upon our customers to let us know what they need in
a communications library. This means we are committed to providing
the best communications library that we can. If you have any
suggestions or comments, please let us know.
If you are having a problem using WSC4D, call us at 205-881-4630
between 1:30 PM and 9:30 PM CST Monday through Friday. You can also
call at other times and leave a message, and call back later for a
reply.
However, we can only answer questions with respect to using the WSC4D
library. We cannot help you program your application.
If you are on the Internet, email us at info@marshallsoft.com. You
can also get the latest versions of our products from our anonymous
ftp site:
FTP: ftp.marshallsoft.com PATH: marshallsoft
You may also call our User Support BBS (2400 to 14400 baud, no
parity, 8 data bits, 1 stop bit) at 205-880-9748 and leave a message
(address it to the SYSOP). We will reply within 24 hours.
The BBS is available 24 hours per day except at 2 PM Sundays for
maintenance. All files are in standard ZIP format. The BBS will
contain the latest shareware version of all MarshallSoft products as
well as related files such as:
BUGS.ZIP: Bug report.
NEWS.ZIP: Latest news regarding our products.
The MarshallSoft Computing, Inc. newsletter 'Comm Talk' is published
quarterly. It discusses various communications problems and
solutions using WSC4D as well as related information.
The latest copy of our newsletter can be found on our User Support
BBS (in file area 'Newsletters'), our anonymous ftp site (directory
/marshallsoft) as well as our web site.
Web site: www.marshallsoft.com
1.2 ASP Ombudsman
MarshallSoft Computing, Inc. is a member of the Association of
Shareware Professionals (ASP). ASP wants to make sure that the
shareware principle works for you. If you are unable to resolve a
shareware-related problem with an ASP member by contacting the member
directly, ASP may be able to help. The ASP Ombudsman can help you
resolve a dispute or problem with an ASP member, but does not provide
technical support for members' products. Please write to the ASP
Ombudsman at 545 Grover Road, Muskegon, MI USA 49442-9427, Fax
616-788-2765, or send a CompuServe message via CompuServe Mail to ASP
Ombudsman 70007,3536.
WSC4D Users Manual Page 4
1.3 Determining UART Address & IRQ Settings
You will not normally need to know the port addresses or IRQ
assignments made by Windows. But this information is maintained by
Windows and is available if you need it.
Both Windows 3.X and Windows 95 maintain a list of serial port
settings. On Windows 3.X systems, choose the 'Ports' icon in the
'Control Panel' in the 'Main Group'. Select 'Settings' and then
'Advanced' to view the COM port UART address and IRQ settings.
In Windows 95, choose 'My Computer' icon ('or whatever your computer
icon is named), select the 'Control Panel' folder and then the
'System' icon. Click on the 'Device Manager' tab. Click 'Computer'
and then click 'Properties'. Click the 'View Resources' tab. To view
reserved resources, click the resource type at the top of the dialog
box (i.e., 'Interrupt request (IRQ)' or 'Input/output (I/O)' ).
The four standard COM ports which Windows typically controls are:
Port Address IRQ
COM1 0x3F8 4
COM2 0x2F8 3
COM3 0x3E8 4
COM4 0x2E8 3
WSC4D Users Manual Page 5
1.4 Installation
(1) Before installation of WSC4D, your Delphi compiler should already
be installed on your system and tested. Note that Delphi 2 or Delphi
3 is required in order to create Win32 programs.
Examine the file 'FILES.LST' for a list of the distribution files.
(2) Make a backup copy of your distribution disk. Put your original
distribution disk in a safe place.
(3) Exit Windows into DOS, or start a DOS window:
(4) Create your WSC project directory, copy the WSC archive, then
unzip the archive. For example:
MKDIR WSC
PKUNZIP WSC4D21.ZIP WSC
(5) Run the install program INSTALL.BAT which will copy the correct
files for your installation (Delphi 1.0) or Delphi 2.0).
If you are using Delphi 1 (Win16), then type:
INSTALL 16
If you are using Delphi 2 or Delphi 3, (Win32), then type:
INSTALL 32
The install program creates WSC.PAS from either WSC16.PAS or
WSC32.PAS, and copies the proper DLLs. This way, the source code for
the example programs is identical for both 16-bit Delphi and 32-bit
Delphi.
WSC4D Users Manual Page 6
2.0 Library Overview
2.1 Dynamic Link Libraries
WSC4D includes both Win16 [WSC16] and a Win32 [WSC32] dynamic link
library (DLL). A DLL is characterized by the fact that it need not be
loaded until required by an application program and that only one
copy of the DLL is necessary regardless of the number of application
programs that use it. Contrast this to the traditional static library
which is bound to each and every application that uses it at link
time.
Since WSC4D is a DLL, only one copy of the WSC4D code and data is
loaded into memory regardless of the number of applications programs
that use it. For example, more than one instance of the test program
SIMPLE can be started. All copies of SIMPLE can run concurrently as
long as each uses a different COM port.
2.2 Using the Library
The WSC4D has been tested on a Gateway 2000 25 MHz 80386-DX, a
Gateway 2000 66 MHz 80486-DX2 (Windows 3.1), a Mid-West Micro 150 MHz
Pentium (Windows 95), and a Toshiba Satellite 100 MHz Pentium
(Windows 95).
WSC4D has also been tested with Borland Delphi 1.0 and Delphi 2.0.
Please examine the WSC.PAS file. Note that COM1 is defined as port
zero, not port one. The user must assume the responsibility for
passing the correct information when calling WSC4D functions.
We recommend that you experiment with the example programs.
2.3 Compiling Programs
Each of the example program should be compiled and run. In Delphi,
its easy!
Before beginning, be sure to run INSTALL that will copy the proper
Win16 (or Win32) files.
2.4 Source Code
The source code for WSC.DLL, MIO.DLL, and XYDRIVER.DLL is written in
standard ANSI C, and is included on the registered disk.
To compile these programs from source, the Borland C/C++ Windows
compiler is required.
All source code for the example programs is included in both the
shareware and registered archive. All example programs compile under
both Delphi 1 (Win16) and Delphi 2 (Win32).
The same set of DLLs is used for all WSC products: C/C++ (WSC4C),
Delphi (WSC4D) and Visual Basic (WSC4VB).
WSC4D Users Manual Page 7
3.0 Talking to Your Modem
A modem is used to extend the distance over which you may
communicate. Without a modem, your RS232 cable is limited to a
maximum of approximately 50 feet. But with a modem, you can
communicate literally around the world.
3.1 Modem Standards
Two modems can communicate over a telephone line only if they are
both using the same signaling frequencies and modulation, which are
determined by the modem standards used. Modem standards can be
divided into three sets: (1) speed, (2) data compression used, and
(3) error control.
The Bell standards (103 & 212A) are those of AT&T. The CCITT (The
International Consultative Committee for Telephone and Telegraph)
standards are designated as 'V. '.
Speed
Bell 103 : 300 baud
Bell 212A : 1200 baud
V.21 : 300 baud
V.22bis : 1200 & 2400 baud
V.32 : 4800 & 9600 baud
V.32bis : 4800, 7200, 9600, 12000, and 14400 baud
V.34 : to 28800 baud.
Data Compression
MNP 5 : Microcom Networking Protocol (proprietary).
V.42bis : International data compression standard.
Error Control
MNP 2,3,4 : Three level error correction (public domain).
V.42 : International error correction standard.
WSC4D Users Manual Page 8
3.2 Flow Control
With modems using data compression, the modem to modem connection
will run at various speeds depending on the quality of the line. The
computer to modem connection will be at a fixed baud rate. Therefore,
a protocol (flow control) is necessary to synchronize the data flow
between a modem and the computer to which it is connected. Refer to
your modem manual for information on flow control protocols
supported.
Two flow control protocols are used by most all modems which require
flow control. Software flow control is called 'XON/XOFF' (other
software flow control character pairs are defined but operate the
same as XON/XOFF) and hardware flow control is called 'RTS/CTS'. Most
modems which require flow control enable hardware flow control by
default.
In XON/XOFF (software) flow control, the computer suspends
transmitting data if it receives a XOFF character (13 hex) from the
modem, and continues transmitting when it receives a XON character
(11 hex). Similarly, the computer can signal the modem not to send
any more data by transmitting a XOFF to it, and can tell the modem to
continue transmission be sending a XON.
In RTS/CTS (hardware) flow control, the RTS line is used by the
computer to signal the modem , while the CTS line is used by the
modem to signal the computer. The RTS line is set OFF by the
computer to tell the modem to suspend transmission, and set to ON to
tell the modem to continue transmission. The CTS line is set to OFF
by the modem to tell the computer to stop transmitting, and set to ON
to tell the computer to continue transmitting.
Given the choice, always choose hardware flow control over software
flow control so that all data transmission is transparent. If
hardware flow control is not the default (which it almost always is),
you should modify your modem initialization string to turn hardware
flow control on.
WSC4D supports both hardware and software flow control. Refer to the
SioFlow function in the WSC4D Reference Manual.
NOTE: When hardware flow control is enabled (by calling SioFlow), no
serial I/O can occur until both DSR and CTS are set by the modem.
WSC4D Users Manual Page 9
3.3 Modem Initialization
If your application uses a modem (as opposed to using a null modem
cable), then you should always send an initialization string to your
modem. Communication programs such as PROCOMM and TELIX always send
such a string automatically as soon as they start up.
The particular initialization string depends on the make of your
modem. For most modems, the following string (followed by a carriage
return) should work:
AT E1 S7=60 S11=60 V1 X1 Q0 S0=0
Refer to your Modem User's Guide for a full discussion of these
commands. A brief description is as follows:
AT Modem attention command.
E1 Modem will echo what you send to it.
S7=60 Wait 60 seconds for carrier and/or dial tone.
S11=60 Use 60 milliseconds for tone dialing duration & spacing.
V1 Display result code as words (not numbers).
X1 Use the extended result message (CONNECT XXXX) set.
Q0 Modem displays result codes.
S0=0 Do not answer RING.
If your application will answer incoming calls, then set the S0
register to the ring on which to automatically answer.
If you send the above codes by using SioPutc (as opposed to typing
them from the keyboard), then follow these guidelines:
(1) Send an initial carriage return before the initialization string.
(2) Pause at least 150 milliseconds after each character sent as
your modem needs the time to perform its own internal processing.
Pause a little longer if your modem is not accepting your
initialization string.
(3) Pause one and a half seconds after sending any initialization
command such as ATZ or AT&F since your modem must do quite a bit of
processing.
If you experience any problems in initializing your modem, you should
first reset it to factory settings by sending:
AT&F
NOTE: Use AT&F1 for US Robotics modems.
Refer to the TERM program (function SendToModem is in the file MIO.C)
for an example of sending an initialization string to a modem.
WSC4D Users Manual Page 10
4.0 MODEM I/O (MIO)
4.1 MIO Introduction
The file MIO.PAS contains prototypes for using the Modem I/O DLL.
These functions ease communicating with modems using AT commands. The
TERM example has an example of using the MIO functions.
The Windows 'operating system' is what is called 'cooperative
multitasking' (except Win32). The executing Windows task must
voluntarily 'give up' control before another Windows task (or Windows
itself) can execute. The MIO functions are broken down into parts
called states, and control is returned to Windows between executing
each state.
For example:
(1) Send the string to the MIO driver by executing:
Code := mioSendTo(Port,100,'!ATDT1,205,880,9748');
The '!' characters are converted to carriage returns. The text
string is copied into the driver's data area.
(2) Call mioDriver (typically based on a timer) until MIO_IDLE is
returned. Each time mioDriver is called, it will send another
character to the modem provided the required delay (since the
previous character was sent) has passed. If the delay has not
passed, the driver simply returns MIO_RUNNING, but without actually
sending a character to the modem. Once all characters have been
sent, mioDriver will return MIO_IDLE, indicating it is done and is
ready to accept another function.
mioDriver will return MIO_RUNNING if it is still processing. Anything
else indicates that it is still processing and the returned value is
a character from the modem that can be displayed if wanted.
(3) Once mioDriver returns MIO_IDLE, call mioResult to get the result
of the mioSendTo call.
4.2 MIO Function Summary
mioDriver : Drives the execution of mioSendTo, mioWaitFor, or
mioQuiet once they have been started.
mioBreak : Forces the MIO driver to IDLE state.
mioSendTo : Sends a string (including control chars) to the modem.
mioWaitFor : Waits for a particular string from the modem, passing
all else through.
mioQuiet : Waits for continuous quiet of a specified duration.
mioBreak : Breaks further modem I/O activity.
Refer to the WSC Reference Manual for more information.
WSC4D Users Manual Page 11
5.0 XMODEM & YMODEM
5.1 XYDRIVER Introduction
The XMODEM & YMODEM functions are implemented in XYDRIVER as a DLL
(Dynamic Link Library), and are state driven like the Modem I/O
functions described in the previous section. The TERM program
provides an example of using XYDRIVER.
Files can be sent and received using XMODEM, XMODEM/CRC, XMODEM/1K,
and YMODEM. The basic procedure used to run XMODEM or YMODEM is as
follows:
(1) Call xyAcquire immediately after calling SioReset.
(2) To receive a file, call xyStartRx, then call xyDriver
repeatedly until XY_IDLE is returned.
(3) To send a file, call xyStartTx, then call xyDriver repeatedly
until XY_IDLE is returned.
(4) Call xyRelease immediately before calling SioDone.
5.2 XYDRIVER Function Summary
xyAbort : Abort driver at any time.
xyAcquire : Acquire a port.
xyDebug : Set the debug level.
xyDriver : Executes the next state or states.
xyGetMessage : Get the next debug message.
xyGetParameter : Get a driver parameter.
xyRelease : Release a port.
xyStartRx : Start a receive.
xyStartTx : Start a transmit.
Refer to the WSC Reference Manual for more information.
WSC4D Users Manual Page 12
6.0 Problems
If you cannot get your application to run properly, first compile and
run the terminal emulator program SIMPLE provided on your
distribution disk. Test SIMPLE by connecting two computers with a
null modem cable or by commanding a Hayes AT command set compatible
modem.
Once EASY runs, compile and run the SELFTEST program. This program
will test your serial ports' functionality.
If your application does not run but EASY and SELFTEST run correctly,
then you have most likely made a programming mistake in your
application. MarshallSoft Computing cannot debug your application,
especially over the telephone! However, consider each of the
following when searching for an error in your application.
1. Have you included the file WSC.PAS in your application ?
2. Are your receive and transmit buffers large enough ? Use a buffer
size that is twice the size of the largest expected block.
3. Have you selected too high a baud rate? Windows can multitask
many tasks at once. You may have to lower your baud rate (or get
16550 UARTS).
4. Did SioReset return a zero value ? If not, then you must call
SioReset again. See EASY_PGM.PAS for an example.
5. Did you send the proper initialization string to your modem ?
Did you set DTR and RTS? (you should).
7. Are you trying to link a 32-bit DLL to a 16-bit program (or vice
versa)? Keep Win16 (Delphi 1) & Win32 (Delphi 2) development
separate.
We recommend the following steps if you believe that you have
discovered a bug in the library: (1) Create the smallest, simplest
test program possible that demonstrates the problem. (2) Document
your exact machine configuration and what error the test program
demonstrates. (3) Upload the example source to our user support BBS,
email it or mail us a disk.
If the problem can be solved with an easy work-around, we will
publish the work-around. If the problem requires a modification to
the library, we will make the change and make the modified library
available to our customers without charge.
WSC4D Users Manual Page 13
7.0 Serial Communications
7.1 Communications Basics
The heart of serial communications is the UART (Universal
Asynchronous Receiver Transmitter). The IBM PC/XT/AT and
compatibles use the 8250, 16450, or the 16550 UART. The purpose of
the UART is:
(1) To convert bytes from the CPU (Central Processing Unit), into a
serial format by adding the necessary start, stop, and parity bits to
each byte before transmission, and to then transmit each bit at the
correct baud rate.
(2) To convert the incoming stream (at a specified baud rate) of
serial bits into bytes by removing the start, stop, and parity bits
before being made available to the CPU.
The UART is part of the serial interface circuitry which allows the
CPU to send and receive signals over the RS232 lines. This can be
diagrammed as follows:
Serial Interface
+-------------------+
| |
+-----+ Data Bus | +------+ | RS232 Signals
| CPU +------------+ | UART | +----------------*
+-----+ | +------+ |
| |
+-------------------+
The 8250/16450/16550 UART is capable of operating in one of two
modes, 'polled' and 'interrupt driven'. The serial communications
functions in the BIOS use the polled method. In this approach, the
CPU is typically in a loop asking the UART over and over again if it
has a byte ready. If its does, the polling code returns the byte.
But, if the next byte comes in before the polling code is executing
again, then that byte is lost.
In the interrupt driven approach (used by Windows/WSC4D), when a byte
is received by the UART, an 'Interrupt Service Routine' (ISR) is
executed immediately, suspending temporarily whatever else is
executing. The ISR then moves the byte to a buffer so that your
application program can later read it.
Transmitted bytes are queued up awaiting transmission. When a byte
is moved from the UART transmitter holding register to the UART
transmitter shift register, an interrupt is generated and the next
byte is taken from the library transmitter buffer by the ISR and
written to the UART holding register.
Up to 16 bytes can be taken from the transmitter buffer while
processing one transmitter interrupt if an 16550 UART is used. The
16550 UART is strongly recommended for computers doing serial
communications under Windows.
WSC4D Users Manual Page 14
7.2 RS-232 Signals
RS-232 is the name of the serial data interface standard used to
connect computers to modems. Most IBM compatible computers are built
with at least one serial port and use either DB9 (9 pin) or DB25 (25
pin) connectors.
A summary of these pins and their function follows. For more
detailed information, refer to one of the many books dealing with
RS-232 interfacing.
Signal Ground Pin 7 (DB25), Pin 5 (DB9)
The SG line is used as the common signal ground, and must always be
connected.
Transmit Data Pin 2 (DB25), Pin 3 (DB9)
The TX line is used to carry data from the computer to the modem.
Receive Data Pin 3 (DB25), Pin 2 (DB9)
The RX line is used to carry data from the modem to the computer.
Data Terminal Ready Pin 20 (DB25), Pin 4 (DB9)
The DTR line is used by the computer to signal the modem that it is
ready. DTR should be set high when talking to a modem.
Data Set Ready Pin 6 (DB25), Pin 6 (DB9)
The DSR line is used by the modem to signal the computer that it is
ready.
Request to Send Pin 4 (DB25), Pin 7 (DB9)
The RTS line is used to 'turn the line around' in half duplex modems,
and for hardware flow control in most modems that require flow
control. RTS is controlled by the computer and read by the serial
device (modem).
Clear to Send Pin 5 (DB25), Pin 8 (DB9)
The CTS line is used to 'turn the line around' in half duplex modems,
and for hardware flow control in most modems that require flow
control. CTS is controlled by the serial device (modem) and read by
the computer.
Data Carrier Detect Pin 8 (DB25), Pin 1 (DB9)
The DCD line is used by the modem to signal the computer that a data
carrier signal is present.
Ring Indicator Pin 22 (DB25), Pin 9 (DB9)
The RI line is asserted when a 'ring' occurs.
WSC4D Users Manual Page 15
8.0 Example Programs
8.1 EASY
EASY (EASY_PRJ) is a very simple communications program using WSC4D.
Everything that is typed on the keyboard is sent to the serial port,
and everything incoming from the serial port is displayed on the
screen.
The easiest way to test EASY is to connect to a modem. Typing 'AT'
should result in an 'OK' being displayed.
A null-modem cable can also be used to connect two computers together
with their serial ports. Run EASY on both machines. Whatever is typed
on one machine will be displayed on the other.
8.2 SELFTEST
SELFTEST (SELF_PRJ) performs a serial port I/O functionality test.
Either a pair of ports on the same computer (using a null modem
cable) or a single port (using a loopback adapter) can be tested.
Refer to LOOPBACK.TXT for an explanation of how to make a loopback
adapter (without tools!).
8.3 MODEM
MODEM (MODM_PRJ) is similar to EASY, but with enhanced capability. It
can set flow control (hardware, software, or none), DTR line (set or
clear), RTS line (set or clear), display the transmit & receive queue
sizes, detect a break signal, detect changes in DSR and CTS, as well
as check for various line errors (parity error, framing error, data
overrun, receive queue overflow, and transmit buffer full).
8.4 TERM
TERM (TERM_PRJ) is a simple terminal emulator suitable for calling up
a BBS (such as ours) and downloading or uploading files using XMODEM
or YMODEM. The TERM program uses MIO.DLL for modem control commands,
and the XYDRIVER.DLL for XMODEM & YMODEM file transfer.
Selecting 'Dial' from the menu bar will result in a pop-up dialog
requesting the phone number to dial. Once entered, the number is
dialed, and the program will wait for up to 60 seconds for the
'CONNECT' string from the modem. This wait can be terminated at any
time by choosing 'BREAK' on the menu bar.
Once logged on, files can be uploaded or downloaded by selecting
'Send' or 'Receive' from the menu bar. To abort a file transfer,
choose 'BREAK' from the menu bar then type a series of Ctrl-X (^X)
characters from the keyboard.
8.5 FIND
FIND (FIND_PRJ) searches your computer for attached modems. Just
start FIND and select "FindModem" on the menu bar.
WSC4D Users Manual Page 16
9.0 Legal Issues
9.1 Registration
WSC4D may be registered for $75 plus $5 S&H ($10 outside of North
America).
To order, contact us as shown on the title page of this manual. All
prices are guaranteed for one year from the release date.
Multiple copy discounts (3 or more) and site licenses are available.
Please call for details.
We accept American Express, VISA, MasterCard, Discover, US dollars
drawn on a US bank, International Postal Money Orders, purchase
orders (POs) from recognized US schools and companies listed in Dun &
Bradstreet, and COD (street address and phone number required) within
the USA (plus a $4.50 COD charge).
For credit card orders, be sure to include the account number, the
expiration date, the exact name on the card, and the complete card
billing address (the address to which the credit card bill is
mailed).
Print the file INVOICE.TXT if a 'Pro Forma' invoice is needed.
If you wish to update from an older version of WSC4D, send $25 plus
$5 S&H ($10 S&H outside of North America).
The registered package includes:
o Win16 & Win32 WSC4D Libraries w/o shareware screens.
o Win16 & Win32 source code for WSC, MIO, and XYDRIVER.
o Printed Users Manual & Reference Manual.
o Telephone, BBS, and email support for one year.
The registered user will receive the latest version of WSC4D shipped
by US second day priority mail (packet airmail overseas). A 3.5' HD
diskette is provided.
WSC4D Users Manual Page 17
9.2 License
MarshallSoft Computing, Inc. grants the registered user of WSC4D the
right to use one copy of the WSC4D library (in object form) on a
single computer in the development of any software product (other
more than one computer at the same time. The source code for the
library (WSC16.C, WSC32.C, MIO.C, and XYDRIVER.C) is copyrighted by
MarshallSoft Computing and may not be released in whole or in part.
Products developed using WSC4D may be distributed without royalty.
9.3 Warranty
MARSHALLSOFT COMPUTING, INC. DISCLAIMS ALL WARRANTIES RELATING TO
THIS SOFTWARE, WHETHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT
LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY AND
SPECIFICALLY DISCLAIMED. NEITHER MARSHALLSOFT COMPUTING, INC. NOR
ANYONE ELSE WHO HAS BEEN INVOLVED IN THE CREATION, PRODUCTION, OR
DELIVERY OF THIS SOFTWARE SHALL BE LIABLE FOR ANY INDIRECT,
CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT OF THE USE OR
INABILITY TO USE SUCH SOFTWARE EVEN IF MARSHALLSOFT COMPUTING, INC.
HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR CLAIMS. IN NO
EVENT SHALL MARSHALLSOFT COMPUTING, INC.'S LIABILITY FOR ANY SUCH
DAMAGES EVER EXCEED THE PRICE PAID FOR THE LICENSE TO USE THE
SOFTWARE, REGARDLESS OF THE FORM OF THE CLAIM. THE PERSON USING THE
SOFTWARE BEARS ALL RISK AS TO THE QUALITY AND PERFORMANCE OF THE
SOFTWARE.
Some states do not allow the exclusion of the limit of liability for
consequential or incidental damages, so the above limitation may not
apply to you.
This agreement shall be governed by the laws of the State of Alabama
and shall inure to the benefit of MarshallSoft Computing, Inc. and
any successors, administrators, heirs and assigns. Any action or
proceeding brought by either party against the other arising out of
or related to this agreement shall be brought only in a STATE or
FEDERAL COURT of competent jurisdiction located in Madison County,
Alabama. The parties hereby consent to in personam jurisdiction of
said courts.
WSC4D Users Manual Page 18
10.0 Summary
10.1 Revision History
Version 2.0: 17 February, 1997.
o Includes Win16 (Delphi 1) and Win32 (Delphi 2) libraries.
o Added XMODEM & YMODEM DLL (XYDRIVER.DLL).
o Added TERM example program.
Version 2.1: 9 June, 1997.
o Screen display uses MEMO class.
o WIN32 version can display error text from Win32 Windows.
o Added FIND example program.
o Added SioRead function.
o SioInfo can return seconds to expiration [SHAREWARE].
10.2 WSC Function Summary
Refer to the WSC4D Reference Manual (WSC4D_R.TXT) for detailed
information on the communications and support functions. A one line
summary of each function follows:
+-------------+-----------------------------------------------------+
| SioBaud | Sets the baud rate of the selected port. |
| SioBrkSig | Asserts, cancels, or detects BREAK signal. |
| SioCTS | Reads the Clear to Send (CTS) modem status bit. |
| SioDCD | Reads the Data Carrier Detect (DCD) modem status. |
| SioDone | Terminates further serial processing. |
| SioDSR | Reads the Data Set Ready (DSR) modem status bit. |
| SioDTR | Set, clear, or read the Data Terminal Ready (DTR). |
| SioFlow | Enables / disables hardware flow control. |
| SioGetc | Reads the next character from the serial line. |
| SioGets | Reads a string of characters. |
| SioInfo | Returns information such as library version. |
| SioParms | Sets parity, stop bits, and word length. |
| SioPutc | Transmit a character over a serial line. |
| SioPuts | Transmits a string of characters. |
| SioRead | Reads any UART register directly from hardware. |
| SioReset | Initialize a serial port for processing. |
| SioRI | Reads the Ring Indicator (RI) modem status bit. |
| SioRTS | Sets, clears, or reads the Request to Send (RTS). |
| SioRxClear | Clears the receive buffer. |
| SioRxQue | Returns the number of characters in the RX queue. |
| SioStatus | Returns the serial port line status. |
| SioTxClear | Clears the transmit buffer. |
| SioTxQue | Returns the number of characters in the TX queue. |
| SioUnGetc | 'Ungets' (puts back) a specified character. |
+-------------+-----------------------------------------------------+
WSC4D Users Manual Page 19
10.3 Further Reading
The best way to learn about serial communications is to read a good
book on the subject. Several good texts are available. Two that I
like are:
(1) C Programmer's Guide to Serial Communications by Joe Campbell
(SAMS) (2) Mastering Serial Communications by Peter Gofton (SYBEX).
You may also want to get a copy of one of our communications products
which talks to the hardware directly. They include more hardware
specific documentation.
11.0 Other MarshallSoft Computing Products
Several shareware products are available from MarshallSoft Computing.
11.1 The Personal Communications Library for Windows (C/C++)
The Personal Communications Library for Windows (PCL4W) is a Windows
based [Win16] asynchronous communications library designed for
software developers programming in C/C++. Unlike WSC4D, PCL4W
interfaces to the serial port hardware directly. PCL4W also supports
multiport boards such as those made by DigiBoard and BOCA.
The Personal Communications Library for Windows (PCL4W) is available
for $75 plus $5 S&H ($10 S&H overseas).
11.2 The Personal Communications Library for Pascal / DOS
PCL4P is similar to PCL4W except that it is designed for DOS.
Includes support for both 16-bit protected mode.
11.3 Libraries for Other Languages
We have communications libraries for C/C++, Turbo Pascal, Visual
Basic, and PowerBASIC.
PCL4C : C/C++, DOS [include 16-bit & 32-bit protected mode].
PCL4P : Turbo Pascal, DOS [includes 16-bit protected mode].
PCL4VB : Visual Basic, DOS.
PCL4PB : Power Basic, DOS.
PCL4W : C/C++, Windows 3.1 & Win 95, talks to hardware directly.
PCLVBW : Visual Basic, Win 3.1 & Win 95, talks to hardware directly.
WSC4C : C/C++, Win 3.1, Win 95, Win NT. Uses Windows API.
WSC4VB : Visual Basic, Win 3.1, Win 95, Win NT. Uses Windows API.
WSC4D : Borland Delphi, Win 3.1, Win 95, Win NT. Uses Windows API.
WSC4D Users Manual Page 20